Set generate without sourcecode as a default to sphinx to reduce spac… #279

WolfgangFischerEtas · 2025-10-20T07:56:30Z

…e in the gh_pages by approx. 10%. Add option to generate sourcecode via bazel //:docs -- --sphinx_args -t source

📌 Description

There is only 1GB of space available in gh-pages. Therefore, websites created through PR or updates on mein should be as small as possible. For optimization purposes, I have therefore disabled the source code. If necessary, it can be regenerated using an option in the bazel call.

🚨 Impact Analysis

This change does not violate any tool requirements and is covered by existing tool requirements
This change does not violate any design decisions
Otherwise I have created a ticket for new tool qualification

✅ Checklist

Added/updated documentation for new or changed features
Added/updated tests to cover the changes
Followed project coding standards and guidelines

…e in the gh_pages by approx. 10%. Add option to generate sourcecode via bazel //:docs -- --sphinx_args -t source

github-actions · 2025-10-20T07:57:32Z

License Check Results

🚀 The license check job ran with the Bazel command:

bazel run //src:license-check

Status: ⚠️ Needs Review

Click to expand output

[License Check Output]
Extracting Bazel installation...
Starting local Bazel server (8.3.0) and connecting to it...
INFO: Invocation ID: 745c80ad-195d-46c7-855f-63baaf88b5b8
Computing main repo mapping: 
Computing main repo mapping: 
Loading: 
Loading: 0 packages loaded
Loading: 0 packages loaded
    currently loading: src
Analyzing: target //src:license-check (1 packages loaded, 0 targets configured)
Analyzing: target //src:license-check (1 packages loaded, 0 targets configured)

Analyzing: target //src:license-check (71 packages loaded, 9 targets configured)

Analyzing: target //src:license-check (73 packages loaded, 9 targets configured)

Analyzing: target //src:license-check (123 packages loaded, 2288 targets configured)

Analyzing: target //src:license-check (134 packages loaded, 2484 targets configured)

Analyzing: target //src:license-check (134 packages loaded, 2484 targets configured)

INFO: Analyzed target //src:license-check (137 packages loaded, 4500 targets configured).
[11 / 13] Creating runfiles tree bazel-out/k8-opt-exec-ST-d57f47055a04/bin/external/score_tooling+/dash/tool/formatters/dash_format_converter.runfiles [for tool]; 0s local
INFO: Found 1 target...
Target //src:license.check.license_check up-to-date:
  bazel-bin/src/license.check.license_check
  bazel-bin/src/license.check.license_check.jar
INFO: Elapsed time: 12.766s, Critical Path: 0.45s
INFO: 13 processes: 4 disk cache hit, 9 internal.
INFO: Build completed successfully, 13 total actions
INFO: Running command line: bazel-bin/src/license.check.license_check src/formatted.txt <args omitted>
usage: org.eclipse.dash.licenses.cli.Main [-batch <int>] [-cd <url>]
       [-confidence <int>] [-ef <url>] [-excludeSources <sources>] [-help] [-lic
       <url>] [-project <shortname>] [-repo <url>] [-review] [-summary <file>]
       [-timeout <seconds>] [-token <token>]

github-actions · 2025-10-20T08:06:55Z

The created documentation from the pull request is available at: docu-html

src/extensions/score_sphinx_bundle/__init__.py

src/incremental.py

a-zw · 2025-10-21T08:31:17Z

src/extensions/score_sphinx_bundle/__init__.py

 def setup(app: Sphinx) -> dict[str, object]:
+
+    # Tag-recognition
+    if app.tags.has("source"):


Why use tags here? I don't think they are designed for such configuration purposes?

Yes, you're certainly right there, as tags should really be used for conditional passages in the documentation. Of course, I can also make this a generic build option again if that would be better.

I created a patch which removes the 'tag' from the setup function. Instead now a configuration value is used which is the better choice I think. Therefore you have to use bazel run //:docs -- sphinx_args -D enable_source_generation=1 if you want a website with soucecode in it.

nicu1989 · 2025-10-21T08:39:00Z

Do you have some benchmark for the 10% in size reduction? Because the source code linkage only adds some txt files. Also I would prefer if it would be the other way around: to pass a parameter to the bazel command that disables the sourcecode linking, by default being enabled.

…g which shall be used more for content

…core_docs-as-code into feature/sourceopt

ubmarco · 2025-10-22T21:07:03Z

I just built the documentation https://github.com/eclipse-score/score/tree/main/docs.
Output size:

I have not looked into the deployment, but do we delete the .doctrees before deploying? This would save 25% for this build.

ubmarco · 2025-10-22T21:13:00Z

Another option is to look into the _static folder. Maybe not all assets are required.
E.g. does the documentation use datatables?

We could also look into minifying the HTML pages.

WolfgangFischerEtas · 2025-10-23T06:49:13Z

@ubmarco : I will have a look into this, how to remove .doctrees before copying the website to gh-pages.

WolfgangFischerEtas · 2025-10-23T12:07:49Z

@ubmarco : I've looked into the branch gh-pages, in main or the pr-xxxx directories the .doctrees directory is not available. Therefore nothing we can optimize here.

AlexanderLanin · 2025-10-28T21:25:32Z

pass a parameter to the bazel command that disables the sourcecode linking, by default being enabled.

It's not linking. It's embedding the source code redundantly into the html pages. The link remains available either way.

AlexanderLanin · 2025-10-28T21:27:23Z

@ubmarco : I will have a look into this, how to remove .doctrees before copying the website to gh-pages.

Potentially a happy accident that some command ignores .* files. Maybe this one: https://github.com/eclipse-score/cicd-workflows/blob/021c830fe38f89d6867a1200708b80637ee8c1e5/.github/actions/deploy-versioned-pages/action.yml#L62

src/extensions/score_sphinx_bundle/__init__.py

AlexanderLanin · 2025-10-28T21:29:36Z

src/extensions/score_sphinx_bundle/__init__.py

+        if "score_sphinx_bundle.source_code_linker" in app.config.extensions:
+            app.config.extensions.remove("score_sphinx_bundle.source_code_linker")


why remove source code links here as well?

a-zw · 2025-11-04T10:42:58Z

src/extensions/score_sphinx_bundle/__init__.py

+
+    # recognition of configuration value
+    app.add_config_value("enable_source_generation", False, "html")
+    if app.config.enable_source_generation:


We don't need configuration for this. Simply always disable source generation.

…ourcecode' always

a-zw · 2025-11-13T08:30:46Z

src/extensions/score_sphinx_bundle/__init__.py



 def setup(app: Sphinx) -> dict[str, object]:
+    if "score_sphinx_bundle.source_code_linker" in app.config.extensions:


We need the score source linker. This is not about the rst sources but about traceability to C++/Rust sources.

Set generate without sourcecode as a default to sphinx to reduce spac…

3ebf41b

…e in the gh_pages by approx. 10%. Add option to generate sourcecode via bazel //:docs -- --sphinx_args -t source

WolfgangFischerEtas requested review from AlexanderLanin, MaximilianSoerenPollak and dcalavrezo-qorix as code owners October 20, 2025 07:56

github-project-automation bot moved this to Draft in Infrastructure Oct 20, 2025

github-project-automation bot added this to Infrastructure Oct 20, 2025

FScholPer reviewed Oct 20, 2025

View reviewed changes

src/extensions/score_sphinx_bundle/__init__.py Outdated Show resolved Hide resolved

typo in message removed

d5944ad

a-zw reviewed Oct 21, 2025

View reviewed changes

FScholPer previously approved these changes Oct 21, 2025

View reviewed changes

to configure Sphinx a configuration mechanism is used instead of a ta…

3302d02

…g which shall be used more for content

WolfgangFischerEtas dismissed FScholPer’s stale review via 3302d02 October 22, 2025 12:22

WolfgangFischerEtas added 2 commits October 22, 2025 15:01

update code

b2b597e

Merge branch 'feature/sourceopt' of https://github.com/etas-contrib/s…

538a6df

…core_docs-as-code into feature/sourceopt

AlexanderLanin reviewed Oct 28, 2025

View reviewed changes

src/extensions/score_sphinx_bundle/__init__.py Outdated Show resolved Hide resolved

AlexanderLanin reviewed Oct 28, 2025

View reviewed changes

a-zw suggested changes Nov 4, 2025

View reviewed changes

Remove the configuration mechanism, instead use the option 'without s…

e3096f4

…ourcecode' always

WolfgangFischerEtas requested a review from nradakovic as a code owner November 13, 2025 08:02

WolfgangFischerEtas added 2 commits November 13, 2025 09:23

Remove extra argument --sphinx-args which is no longer needed.

d89675f

Remove unused logging lines

163fd80

WolfgangFischerEtas force-pushed the feature/sourceopt branch from 26e7a78 to 163fd80 Compare November 13, 2025 08:27

a-zw approved these changes Nov 13, 2025

View reviewed changes

Must keep source linker

1adac8c

AlexanderLanin approved these changes Dec 10, 2025

View reviewed changes

AlexanderLanin merged commit c87cd89 into eclipse-score:main Dec 10, 2025
13 checks passed

AlexanderLanin deleted the feature/sourceopt branch December 10, 2025 11:05

github-project-automation bot moved this from Draft to Done in Infrastructure Dec 10, 2025

		if "score_sphinx_bundle.source_code_linker" in app.config.extensions:
		app.config.extensions.remove("score_sphinx_bundle.source_code_linker")



		def setup(app: Sphinx) -> dict[str, object]:
		if "score_sphinx_bundle.source_code_linker" in app.config.extensions:

Set generate without sourcecode as a default to sphinx to reduce spac… #279

Set generate without sourcecode as a default to sphinx to reduce spac… #279

Uh oh!

Conversation

WolfgangFischerEtas commented Oct 20, 2025

📌 Description

🚨 Impact Analysis

✅ Checklist

Uh oh!

github-actions bot commented Oct 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

License Check Results

Uh oh!

github-actions bot commented Oct 20, 2025

Uh oh!

Uh oh!

Uh oh!

a-zw Oct 21, 2025

Choose a reason for hiding this comment

Uh oh!

WolfgangFischerEtas Oct 21, 2025

Choose a reason for hiding this comment

Uh oh!

develloup Oct 22, 2025

Choose a reason for hiding this comment

Uh oh!

nicu1989 commented Oct 21, 2025

Uh oh!

ubmarco commented Oct 22, 2025

Uh oh!

ubmarco commented Oct 22, 2025

Uh oh!

WolfgangFischerEtas commented Oct 23, 2025

Uh oh!

WolfgangFischerEtas commented Oct 23, 2025

Uh oh!

AlexanderLanin commented Oct 28, 2025

Uh oh!

AlexanderLanin commented Oct 28, 2025

Uh oh!

Uh oh!

AlexanderLanin Oct 28, 2025

Choose a reason for hiding this comment

Uh oh!

a-zw Nov 4, 2025

Choose a reason for hiding this comment

Uh oh!

a-zw Nov 13, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

github-actions bot commented Oct 20, 2025 •

edited

Loading